/*
 * Package il.ac.biu.cs.grossmm.api.presence
 * File Registrar.java
 * 
 * This is a part of presence service framework API. 
 * See javadoc for more information.
 *  
 * Copyright (C) 2006 Grossmann Mark
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.

 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */
package il.ac.biu.cs.grossmm.api.presence;

import il.ac.biu.cs.grossmm.api.OperationFailedException;

/**
 * The purpose of this interface is to manage entities and their identifiers. An
 * identifier must be uniquely assigned. In other words two entities may not
 * share the same identifier. Each entity has one or more identifiers associated
 * with it.
 * <p>
 * When entity is registered, an initial identifier must be provided. Additional
 * identifiers for an entity may be registered or deregistered anytime. An
 * entity is deregistered on explicit request or when the last identifier for
 * this entity has been deregistered.
 * <p>
 * When an entity is deregistered any publication data associated with it on
 * publication points is removed automatically.
 */
public interface Registrar {
	/**
	 * Gets an entity by one of its identifiers.
	 * 
	 * @param identifier
	 *            entity identifier
	 * @return entity with this identifier
	 */
	Entity getEntity(String identifier) throws OperationFailedException;

	/**
	 * Registers a new entity with a given identifier.
	 * 
	 * @param identifier
	 *            a string to identify the entity
	 * @return the newly registered entity
	 */
	Entity registerEntity(String identifier, EntityType entityType) throws OperationFailedException;

	/**
	 * Register alternative identifier for a given entity
	 * 
	 * @param entity
	 *            the entity to give additional identifier to
	 * @param identifier
	 *            the new identifier for this entity
	 */
	void registerAlias(Entity entity, String identifier) throws OperationFailedException;

	/**
	 * Deregisters entity identifier.
	 * 
	 * @param identifier
	 *            entity identifier
	 * @return true iff the entity was also deregistered because it had no more
	 *         identifiers
	 */
	boolean deregisterAlias(String identifier) throws OperationFailedException;

	/**
	 * Adds a role to the entity by associating the entity with corresponding
	 * entity type.
	 * 
	 * @param entity
	 *            the entity to add a role to
	 * @param entityType
	 *            entity type which represents the role
	 */
	void registerRole(Entity entity, EntityType entityType) throws OperationFailedException;
	
	/**
	 * Removes a role association for entity by disassociating the entity from 
	 * the corresponding entity type.
	 * 
	 * @param entity
	 *            the entity to add a role to
	 * @param entityType
	 *            entity type which represents the role
	 * @return true iff the entity was also deregistered because it had no more
	 *         identifiers        
	 */
	boolean deregisterRole(Entity entity, EntityType entityType) throws OperationFailedException;

	/**
	 * Sets a property for the entity.
	 * 
	 * @param entity
	 *            the entity to update
	 * @param property
	 *            the property to update
	 * @param value
	 *            the new value of the property, should not be null
	 */
	void setProperty(Entity entity, String property, Object value) throws OperationFailedException;

	/**
	 * Gets a property of the entity.
	 * 
	 * @param entity
	 *            the entity of interest
	 * @param property
	 *            the property of interest
	 * @return value of the property or null if there is no such property for
	 *         this entity 
	 */
	<T> T getProperty(Entity entity, String property) throws OperationFailedException;

	/**
	 * Removes a property
	 * 
	 * @param entity
	 *            the entity
	 * @param property
	 *            the property to remove
	 */
	void removeProperty(Entity entity, String property) throws OperationFailedException;

	/**
	 * Deregisters entity along with all its identifiers
	 * 
	 * @param entity
	 *            the entity to deregister
	 */
	void deregister(Entity entity) throws OperationFailedException;
}
